Table Of Contents

• Table Of Contents
• Introduction
• Developing Services
  • Character Set Handling
  • XML Namespace Handling
  • Wildcard Support
  • Handling Empty Fields
  • Handling Paged Results
  • Error Handling
• Deployment
  • Local Services
  • Remote Services
  • Local Vs Remote Services
• Comments / Feedback

Introduction

An EbrService is a component offered by an EbrNode that provides some valuable operation, e.g. it may offer a company report when given a company number, or produce an image of the company's latest set of accounts, or simply return a confirmation that the EbrNode is still active.

Each EbrService has a unique EbrServiceId and performs a single defined operation, e.g. to return a Company Profile. The task of EbrDevelopers will be to implement the EbrServices permitted by their DataSource.

Developing Services

Character Set Handling

All EbrMessages that handle XML EbrMessagePayloads must be encoded in the UTF-8 version of Unicode.

This has obvious implications on any EbrServices you develop as each XML EbrService must be capable of handling UTF-8 encoded strings. Ideally, every EbrGateway and information source would already be UTF-8 enabled, but, of course, this is not always the case.

Typically, your chosen programming environment and toolkits will hide the complexity of the character set conversion, but you should always be aware that the set of data your passing to your information source may contain special characters that your EbrGateway will not be expecting, for example, if your EbrGateway expects only standard ASCII strings, then you must first convert the UTF-8 data to ASCII, losing any special characters entered by the user, or reject the entire message by returning a code of -4 in X-Ebr-Service-Status.

For more information about Unicode and UTF-8, the following links are recommended

http://www.alanwood.net/unicode/Alan Wood's Unicode Resources

http://www-106.ibm.com/developerworks/linux/library/l-linuni.htmlLinux Unicode Programming

http://www.cl.cam.ac.uk/~mgk25/ucs/examples/UTF-8 Examples

http://www.cl.cam.ac.uk/~mgk25/unicode.htmlUnix/Linux Unicode FAQ

http://www.unicode.org/Unicode Home Page

http://www.tldp.org/HOWTO/Unicode-HOWTO.htmlUnicode HOWTO

- NOTE: Note The Content-Type of MessageParts? which contain EBR-XML data must be set to text/xml; charset="utf-8", e.g.

Content-Type: text/xml; charset="utf-8"

XML Namespace Handling

The correct namespace for all EbrMessages that have XML EbrMessagePayloads must be of the following form:

<CompanyProfileReply xmlns="http://ebr.orctel.com/ebr/xml/CompanyProfileReply">
...
...
</CompanyProfileReply>

i.e. the last section of the namespace must match the root element name of the EbrMessage. The leading URL (http://ebr.orctel.com/ebr/xml/) must never be changed.

Wildcard Support

If a field in a EbrMessage request contains an asterisk character (*) as the final character (right-most), that field should be interpreted as a wildcard and the appropriate search procedure created for your information source (if possible).

- NOTE: There is an implicit "AND" association between all fields in an EbrMessage request.

Handling Empty Fields

If your EbrService does not support an optional field in a reply, e.g. FiscalCode in a CompanyProfileReply then you should not set that element in the reply, i.e. it must not appear at all.

Background: it is intended that fields not present in the reply will not be shown at the CommonUserInterface, i.e. the label for the field will not be displayed. Fields that are in the message but empty will will have the label displayed.

However, if you typically support FiscalCode, or the value of FiscalCode is empty coming from your information source then an empty FiscalCode element should appear in the returned message, e.g.

<CompanyProfileReply>
<!-- Mini example -->
<CompanyName>Oracle</CompanyName>
<CompanyNumber>Oracle</CompanyNumber>
<FiscalCode/> <!-- Empty field -->
</CompanyProfileReply>

Note: if the value is a TableCode then you can reference the Code "Empty" in the System table of the EBR TableCodeFile. This Code has the value of an empty string and is useful to prevent the normal debug display of (- - - - -) for an empty table code.

Handling Paged Results

For EbrServices that return a list of results, e.g. CompanySearchReply, there may be cases where the number of items returned in the message (also known as rows, or hits) is not the same as the number of items available from the EbrGateway. For example, a EbrGateway search for "MEDIA" from its local database system may result in 1000 items, but only 100, say, can be returned in the message.

In these cases the EbrGateway should communicate such information via the attributes available within the <DataInfo> structure of the EBR Header structure that is common to all EBR messages.

- NOTE: There is no pre-defined limit for the number of items that can be returned in an EbrMessage.

Error Handling

If you encounter a fatal error condition in the operation of your EbrService you must return the original EbrMessage request that generated the error with one difference - you must alter the X-Ebr-Service-Status EbrMessagePartHeader with the appropriate error code (see ErrorCodeTable).

- NOTE: There is no "EBR Error" type XML schema. Error information is communicated in the EbrMessagePartHeader, separate from the message EbrMessagePayload.

See also: EbrErrorScenarios

Deployment

EbrServices can be deployed either as dynamic extensions to an EbrNode (LocalService) or can alternatively be hosted within a privately developed custom server process (EbrGateway) for handling EbrService interactions (RemoteServices).

Local Services

When an EbrNode receives a message for itself (i.e. the X-Ebr-Destination of the message part is the same as the ThisNode->Id element in the config.xml file) it first checks to see if the EbrServiceId requested is defined in the list of extension services configured at this Node

From config.xml:

<ServiceList>
<Service name="NetworkPoll" handler="com.orctel.ebr.service.NetworkPollService"/>
<Service name="CompanySearch_1" handler="com.orctel.ebr.gateway.CompanySearchService"/>
<Service name="OfficialProfile_1" handler="my.company.services.OfficialProfile"/>
</ServiceList>

If the Service is registered then the Node calls the (Java) class mapped to handle the EbrService.

Remote Services

If a request for NonRegisteredEbrService is received then the EbrNode forwards the exact message onto the configured "=GatewayNode=" server. The "=GatewayNode=" (EbrGateway) server gives EbrDevelopers the opportunity to access the exact same message received by the EbrNode they have installed by deploying a custom server to handle EbrMessages.

The EbrGateway can be written in any language that can handle TCP/IP socket communication. Implementation details are left to the operator. An example EbrGateway and source code can be found as part of the Core Software distribution.

Because the EbrServices are separate from the Node itself, we term these RemoteServices.

- NOTE: An EbrNode can provide LocalServices and offer RemoteServices simultaneously. Any request for a EbrService that isn't found in the local list will automatically be sent to a configured EbrGateway offering RemoteServices.

Local Vs Remote Services

The choice of whether to use LocalServices or implement an EbrGateway to handle EbrServices outside of the CoreSoftware is left to the EbrDeveloper.

LocalServices:

• Must be written in Java (or a language that can generate Java byte code, e.g. Jython).

• Require no additional network code development.

RemoteServices:

• Require development, installation and maintenance of an EbrGateway

• New EbrGateway can be written in any language, allowing EbrServices to also be written in any language.

• Gives the EbrOperator full control over EbrService handling.

From here on this document focuses on developing local Java Services to be used within the distributed CoreSoftware but the same processing principles can still be applied to other languages.